{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hosting Capacity\n",
    "\n",
    "The term PV hosting capacity is defined as the maximum PV capacity which can be connected to a specific grid, while still complying with relevant grid codes and grid planning principles. \n",
    "\n",
    "Here we will introduce a basic algorithm to calculate PV hosting capacity with pandapower.\n",
    "\n",
    "The basic idea of calculating hosting capacity is to increase PV installation until a violation of any planning principle or constraint occurs. To analyse hosting capacity, we need three basic building blocks:\n",
    "1. Evaluating constraint violations\n",
    "2. Chosing connection points for new PV plants\n",
    "3. Defining the installed power of new PV plants "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Evaluation of constraint violations\n",
    "\n",
    "Our example function that evaluates constraint violation is defined as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower as pp\n",
    "\n",
    "def violations(net):\n",
    "    pp.runpp(net)\n",
    "    if net.res_line.loading_percent.max() > 50:\n",
    "        return (True, \"Line \\n Overloading\")\n",
    "    elif net.res_trafo.loading_percent.max() > 50:\n",
    "        return (True, \"Transformer \\n Overloading\")\n",
    "    elif net.res_bus.vm_pu.max() > 1.04:\n",
    "        return (True, \"Voltage \\n Violation\")\n",
    "    else:\n",
    "        return (False, None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function runs a power flow and then checks for line loading and transformer loading (both of which have to be below 50%) and for voltage rise (which has to be below 1.04 pu). The function returns a boolean flag to signal if any constraint is violated as well as a string that indicates the type of constraint violation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Chosing a connection bus\n",
    "\n",
    "If new PV plants are installed, a connection bus has to be chosen. Here, we chose one random bus of each of the buses that have a load connection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy.random import choice\n",
    "\n",
    "def chose_bus(net):\n",
    "    return choice(net.load.bus.values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Chosing a PV plant size\n",
    "\n",
    "The function that returns a plant size is given as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy.random import normal\n",
    "\n",
    "def get_plant_size_mw():\n",
    "    return normal(loc=0.5, scale=0.05)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This function returns a random value from a normal distribution with a mean of 0.5 MW and a standard deviation of 0.05 MW. Depending on the existing information, it would also be possible to use other probability distributions, such as a Weibull distribution, or to draw values from existing plant sizes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Evaluating Hosting Capacity\n",
    "\n",
    "We now use these building blocks to evaluate hosting capacity in a generic network. We use the MV Oberrhein network from the pandapower networks package as an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower.networks as nw\n",
    "def load_network():\n",
    "    return nw.mv_oberrhein(scenario=\"generation\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The hosting capacity is then evaluated like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "iterations = 50\n",
    "results = pd.DataFrame(columns=[\"installed\", \"violation\"])\n",
    "\n",
    "for i in range(iterations):\n",
    "    net = load_network()\n",
    "    installed_mw = 0\n",
    "    while 1:\n",
    "        violated, violation_type = violations(net)\n",
    "        if violated:\n",
    "            results.loc[i] = [installed_mw, violation_type]\n",
    "            break\n",
    "        else:\n",
    "            plant_size = get_plant_size_mw()\n",
    "            pp.create_sgen(net, chose_bus(net), p_mw=plant_size, q_mvar=0)\n",
    "            installed_mw += plant_size"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This algorithm adds new PV plants until a violation of any constraint occurs. Then, it saves the installed PV capacity. This is carried out for a number of iteration (here: 50) to get a distribution of hosting capacity values depending on connection points and plant sizes.\n",
    "\n",
    "The results can be visualized using matplotlib and seaborn:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 720x360 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "plt.rc('xtick', labelsize=18)    # fontsize of the tick labels\n",
    "plt.rc('ytick', labelsize=18)    # fontsize of the tick labels\n",
    "plt.rc('legend', fontsize=18)    # fontsize of the tick labels\n",
    "plt.rc('axes', labelsize=20)    # fontsize of the tick labels\n",
    "plt.rcParams['font.size'] = 20\n",
    "\n",
    "import seaborn as sns\n",
    "sns.set_style(\"whitegrid\", {'axes.grid' : False})\n",
    "\n",
    "fig, axes = plt.subplots(nrows=1, ncols=2, figsize=(10,5))\n",
    "ax = axes[0]\n",
    "sns.boxplot(results.installed, width=.1, ax=ax, orient=\"v\")\n",
    "ax.set_xticklabels([\"\"])\n",
    "ax.set_ylabel(\"Installed Capacity [MW]\")\n",
    "\n",
    "ax = axes[1]\n",
    "ax.axis(\"equal\")\n",
    "results.violation.value_counts().plot(kind=\"pie\", ax=ax,  autopct=lambda x:\"%.0f %%\"%x)\n",
    "ax.set_ylabel(\"\")\n",
    "ax.set_xlabel(\"\")\n",
    "sns.despine()\n",
    "plt.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Note that this is only an example for a basic algorithm in order to demonstrate how such problems can be tackled with pandapower. Algorithms applied in real case studies might include Q-control of PV plants, transformer tap controllers, more sophisticated distribution of PV plants, probability distribution different buses, binary search for the hosting capacity evaluation etc."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
